package com.zenithmind.document.service;

/**
 * 文档访问控制服务接口
 * 遵循接口隔离原则：只包含访问控制相关的方法
 * 遵循单一职责原则：专注于文档访问控制逻辑
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
public interface DocumentAccessControlService {

    /**
     * 检查文档访问权限
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param action 操作类型（view, edit, delete, download, convert等）
     * @return 是否有权限
     */
    Boolean hasPermission(String documentId, String userId, String action);

    /**
     * 验证文档所有权
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 是否为所有者
     */
    Boolean isOwner(String documentId, String userId);

    /**
     * 检查文档是否公开
     * 
     * @param documentId 文档ID
     * @return 是否公开
     */
    Boolean isPublic(String documentId);

    /**
     * 检查用户是否在文档的访问列表中
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 是否在访问列表中
     */
    Boolean isInAccessList(String documentId, String userId);

    /**
     * 检查用户角色是否有权限
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param action 操作类型
     * @return 是否有权限
     */
    Boolean hasRolePermission(String documentId, String userId, String action);

    /**
     * 获取用户对文档的有效权限列表
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 权限列表
     */
    java.util.List<String> getEffectivePermissions(String documentId, String userId);

    /**
     * 记录访问尝试
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param action 操作类型
     * @param success 是否成功
     * @param reason 失败原因（如果失败）
     */
    void recordAccessAttempt(String documentId, String userId, String action, Boolean success, String reason);
}
